<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta http-equiv="X-UA-Compatible" content="chrome=1">
    <link href='https://fonts.googleapis.com/css?family=Chivo:900' rel='stylesheet' type='text/css'>
    <link rel="stylesheet" type="text/css" href="stylesheets/stylesheet.css" media="screen">
    <link rel="stylesheet" type="text/css" href="stylesheets/github-dark.css" media="screen">
    <link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print">
    <!--[if lt IE 9]>
    <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <title>xlunch - application launcher for X</title>
  </head>

  <body>
    <div id="container">
      <div class="inner">

        <header>
          <h1><img src=logo.png width=48 height=48 style="position: relative; top:  8px;"> xlunch</h1>
          <h2>Graphical app launcher for X with few dependencies</h2>
        </header>


        <hr>
        <div id="downloads" class="clearfix" align=center>
          <a href="https://github.com/Tomas-M/xlunch/archive/v4.7.5.zip" id="download-zip" class="button"><span>Download xlunch v4.7.5.zip &nbsp;&nbsp;</span></a>
          <a href="https://github.com/Tomas-M/xlunch/archive/v4.7.5.tar.gz" id="download-tar-gz" class="button"><span>Download xlunch v4.7.5.tar.gz &nbsp;&nbsp;</span></a>
          <a href="https://github.com/Tomas-M/xlunch" id="view-on-github" class="button"><span>View on GitHub &nbsp;&nbsp;</span></a>
        </div>
        <hr>

        <section id="main_content">

<p>Welcome! This is xlunch, the coolest graphical app launcher for Xorg/X11.
It requires only pure Xlib and Imlib2. It allows you to run programs, commands,
or simply select something out of a list using your mouse, keyboard, or both!
UTF8 is fully supported meaning you can have text of all kinds. The prompt
allows you to run arbitrary commands, and it works to filter your entries as
well. xlunch is also highly configurable, both in functionality and style, it
can even be used as a desktop! See below for more</p>

<p><img src="https://raw.githubusercontent.com/Tomas-M/xlunch/Screenshot/screenshot.png" alt="Screenshot" title="Screenshot" style="border: 10px solid #ddd;"></p>
<p><img src="https://raw.githubusercontent.com/Tomas-M/xlunch/Screenshot/screenshot4.png" alt="Screenshot" title="Screenshot" width=758 style="border: 10px solid #ddd;"></p>

<p><strong>Available Modes</strong></p>

<ul style="margin-left: 20px;">
<li style="padding-left: 0">One time launcher mode - this is default mode. There
is no need to specify any commandline parameter for this mode. In this mode, xlunch
opens as a fullscreen application, and offers a screen with icons to select
applications to run, plus commandline which serves as a filter for the icons at
the same time. Running any app or command ends the launcher. You can also cancel
the launcher (by default) with the Esc key, or click with right mouse button.</li>
<li style="padding-left: 0">Desktop mode - this mode is activated with -d. In this mode,
xlunch sends itself to the lowest position in the window stack, so all other windows
are above it. Your window manager will not have any control over it, so xlunch
does not receive any input or focus and it cannot be raised to front. This emulates
desktop with icons. In Desktop mode, applications start using fork (as another process)
and don't terminate the launcher. xlunch in this mode cannot be terminated (except by
killing it with SIGTERM).
</li>
</ul>

<p>Keep in mind that if you use desktop mode while you are running some other desktop already,
you may end up with launcher running under your other desktop, thus it may be inaccessible.
The desktop mode is intended only for users without another desktop (such as WM-only systems
like i3). There are also some other flags that could be of interest in this mode, see below.</p>

<p><img src="https://raw.githubusercontent.com/Tomas-M/xlunch/Screenshot/screenshot2.png" alt="Screenshot" title="Screenshot" style="border: 10px solid #ddd;"></p>
<p><img src="https://raw.githubusercontent.com/Tomas-M/xlunch/Screenshot/screenshot3.png" alt="Screenshot" title="Screenshot" width=758 style="border: 10px solid #ddd;"></p>

<p><strong>Commandline options:</strong></p>

Functional options (these changes what xlunch does, or how it does it):
<pre><code> -d, --desktop                      Desktop mode, always keep the launcher at
                                   background(behind other windows), and ignore ESC
                                   and right mouse click. Combined with --dontquit
                                   xlunch never exits (behaviour of --desktop from
                                   previous versions).
--config [file]                    Reads configuration options from a file. The
                                   options are the same as the long options
                                   specified here. Options that take a value must
                                   have a colon (':') before it's option. It is
                                   also possible to pass the entries along with the
                                   configuration file by using "entries:"
                                   followed by a newline and the regular contents
                                   of an input file
-v, --version                      Returns the version of xlunch
-H, --help                         Shows this help message
--name                             POSIX-esque way to specify the first part of
                                   WM_CLASS (default: environment variable 
                                   RESOURCE_NAME or argv[0])
-N, --notitle                      Do not display any titles under/around icons
-n, --noprompt                     Hides the prompt, only allowing selection
                                   by icon
-o, --outputonly                   Do not run the selected entry, only output it
                                   to stdout
-S, --selectonly                   Only allow an actual entry and not free-typed
                                   commands. Nice for scripting.
-i, --input [file]                 File to read entries from, defaults to stdin
                                   if data is available otherwise it reads from
                                   $HOME/.config/xlunch/entries.dsv or
                                   /etc/xlunch/entries.dsv
-m, --multiple                     Allow multiple instances running
-t, --voidclickterminate           Clicking anywhere that's not an entry terminates
                                   xlunch, practical for touch screens.
--focuslostterminate               When the window loses focus xlunch will quit,
                                   practical for menus
-q, --dontquit                     When an option is selected, don't close xlunch.
                                   Combined with --desktop xlunch
                                   never exits (behaviour of --desktop from
                                   previous versions).
-R, --reverse                      All entries in xlunch as reversly ordered.
-W, --windowed                     Start in windowed mode
--title                            Specifies the title to put on the window when
                                   running in windowed mode.
--icon                             Specifies the icon to put on the window when
                                   running in windowed mode.
-M, --clearmemory                  Set the memory of each entry to null before
                                   exiting. Used for passing sensitive information
                                   through xlunch.
-U, --shortcuts [shortcuts]        Sets shortcuts for the entries, 'shortcuts' is a
                                   string of UTF-8 characters to use sequentially
                                   for the entries provided.
-A, --button [button]              Adds a button to the window. The argument
                                    "button" is a semicolon-separated list on the
                                   form "&lt;icon&gt;;&lt;highlight icon&gt;;&lt;x&gt;,&lt;y&gt;;&lt;command&gt;"
                                   If x or y is negative positioning is relative
                                   to the other side of the screen.
--noscroll                         Disable scroll in xlunch. Ignore entries
                                   that can't fit the screen.
--stdinpolltimeout [i]             How long xlunch should wait (in milliseconds)
                                   for data on stdin before assuming it is
                                   invalid. Use if you find that your xlunch
                                   menu ends up empty on occasion, even though
                                   the entries you pass to xlunch through stdin
                                   are sound. Defaults to 10.
</code></pre>

Style options (these changes how xlunch looks):
<pre><code>-p, --prompt [text]                The prompt asking for input (default: "Run: ")
-f, --font [name]                  Font name including size after slash (default:
                                   "OpenSans-Regular/10" and  "DejaVuSans/10")
-F, --promptfont [name]            Font to use for the prompt
                                   (default: same as --font)
-G, --rootwindowbackground         Use root windows background image
-g, --background [file]            Image to set as background (jpg/png). NOTE: the
                                   background color will be drawn over this image
                                   so use a fully transparent background color if
                                   the image should be drawn as-is.
--bgfill                           Makes the background keep aspect ratio
                                   while stretching
-L, --highlight [file]             Image set as highlighting under selected icon
                                   (jpg/png)
-I, --iconpadding [i]              Padding around icons (default: 10)
    --iconvpadding [i]             Padding around icons (default: Same as --iconpadding)
-T, --textpadding [i]              Padding around entry titles (default: 10)
-c, --columns [i]                  Number of columns to show (without this the max
                                   amount possible is used)
-r, --rows [i]                     Numbers of rows to show (without this the max
                                   amount possible is used)
-b, --border [i]                   Size of the border around the icons and prompt
                                   (default: 1/10th of screen width)
                                   This can also be set to 'auto' in order to
                                   automatically calculate a border taking into
                                   account the margin settings and the
                                   configured columns and rows. You can also specify
                                   border in terms of percentage of screen width by
                                   appending a % sign to the value
-B, --sideborder [i]               Size of the border on the sides, if this is used
                                   --border will be only top and bottom. Similarily
                                   this can be set to 'auto' or a percentage but
                                   then only side borders are calculated
--borderratio [i]                  The ratio of the border to apply above the
                                   content. 0 is no top border, only bottom. 100 is
                                   only top border, no bottom
--sideborderratio [i]              The ratio of the side border to apply to the
                                   left of the content. 0 is no left border, only
                                   right. 100 is only left border, no right
-C, --center                       Center entries when there are fewer entries on a
                                   row than the maximum
-P, --promptspacing [i]            Distance between the prompt and the icons
                                   (default: 48)
-s, --iconsize [i]                 Size of the icons (default: 48)
-a, --textafter                    Draw the title to the right of the icon instead
                                   of below, this option automatically sets
                                   --columns to 1 but this can be overridden.
-O, --textotherside                Draw the text on the other side of the icon from
                                   where it is normally drawn.
-u, --upsidedown                   Draw the prompt on the bottom and have icons
                                   sort from bottom to top.
-X, --paddingswap                  Icon padding and text padding swaps order
                                   around text.
-l, --leastmargin [i]              Adds a margin to the calculation of
                                   application sizes.
-V, --leastvmargin [i]             Adds a vertical margin to the calculation of
                                   application sizes.
-e, --hidemissing                  Hide entries with missing or broken icon images
--tc, --textcolor [color]          Color to use for the text on the format rrggbbaa
                                   (default: ffffffff)
--pc, --promptcolor [color]        Color to use for the prompt text
                                   (default: ffffffff)
--bc, --backgroundcolor [color]    Color to use for the background
                                   (default: 2e3440ff) NOTE: transparent background
                                   color requires a compositor
--hc, --highlightcolor [color]     Color to use for the highlight box
                                   (default: ffffff32)
--scrollbarcolor [color]           Color to use for the scrollbar
                                   (default: ffffff3c)
--scrollindicatorcolor [color]     Color to use for the scrollbar indicator
                                   (default: ffffff70)
</code></pre>

<p>This list of options might seem a bit daunting at first. But you don't have to pass them
all on the command-line. If you specify a configuration file with <code>--config</code>
xlunch will read these options from a configuration file instead. The options have the same
name as their long versions do, but when passed through a configuration file options with
an argument must be split by a colon. If you only have a few entries to pass to xlunch (in
case of a menu for example) they can be passed through the configuration file as well. An
example showing configuration file usage with entries can be seen here:
<code><pre>textafter
columns: 3
rows: 5
iconsize: 64
outputonly
entries:
  Pidgin;extra/pidgin.png;pidgin
  Xterm;extra/terminal.png;xterm
  Firefox;extra/firefox.png;firefox</pre></code>
In this example there are three entries passed to xlunch, note that the whitespace
following each entry is not required, nor is the space between the colon and the arguments
above. Anything after "entries:" will be parsed as an entry, so you can't have more options
below the entries option. Note also that this can be used in conjuction with regular
options. If the options precede the <code>--config</code> option the ones in the file will
override them, and conversely any option following the <code>--config</code> option will
override those in the file. Where the above file to be used like so <code>xlunch --rows 10
  --config file.cfg --columns 2</code> it would lead to xlunch using 5 rows and 2 columns.
Since all the options are the same you can also use the config option in a configuration
file. This means that you can have one config file with your system style of colors and
fonts, and multiple other files loading that file before setting other options like buttons
and entries. Just make sure not to load the same configuration file within that file as it
would lead to an infinite loop.</p>

<p>If you want to completely hide icons (to eg. use xlunch to only select between text entries like
dmenu) you should set <code>--iconsize</code> to 0 and turn on <code>--textafter</code> mode.
This will cause xlunch to remove the extra margin that would normally be around an icon and instead
show only the text. Since the entries in xlunch are normally based on icon size and their padding
this would make each entry super small, but the <code>--textafter</code> mode makes the size of each
entry dependent on the size of the text instead. Note however that this by default sets
<code>--columns</code> to 1, so override it with how many columns of text you would like. When 
<code>--textafter</code> mode is enabled <code>--iconpadding</code> is used on all sides of the
entry box except the right.</p>

<p>There are two different border settings. If you set only <code>--border</code> it will be applied
to all four sides. By setting <code>--sideborder</code> you override the border setting and this new
border size will be used for the right and left border, while the regular border is used for top and
bottom.</p>

<p>For transparent background colors you need to have a compositor installed. This will make the
background of xlunch transparent. Note that the transparency is not additive, meaning that if you set
background to 50% transparency and highlight to 70% transparency the highlighted areas will be 70%
total transparency and not 70% of the 50%, ie. 35%. When a background image is supplied, or the
<code>--rootwindowbackground</code> switch is used xlunch will apply a slight black tint to the image
to make text more readable. By setting the background color manually this color will be used instead,
including transparency, so to disable the tint simply pass a fully transparent color (this does not
require a compositor).

<p>In previous version desktop mode would by default fork of processes instead of terminating. This
is now a separate option (<code>--dontquit</code>) so you can keep xlunch running no matter the
mode.</p>

<p>When using xlunch to create menus of a set of options it might be practical to have shortcuts for
the options. With the <code>--shortcuts</code> option this is achievable. Since this captures
keypresses it might not be very useful without <code>--noprompt</code> but it is all the same
possible (perhaps using the number keys to hotkey the first 10 entries while being able to search
for the rest). As an example usage passing <code>--shortcuts "atf"</code> will apply 'a' as a shortcut
to the first entry, 't' as a shortcut to the second, and 'f' as a shortcut to the third.</p>

<p>To extend the possibilities of xlunch you can also add buttons anywhere in the window with the
<code>--button</code> option. It takes an argument that's a semicolon-separated list on the form:
<code>icon;highlight icon (optional);x,y;command</code>. Note that the highlight icon is optional
and will be used instead of the main icon when you hover over it. If no highlight icon is specified it
will just show the regular icon on hover. So for example the command
<code>--button "./extra/firefox.png;;100,100;firefox"</code> would put the Firefox icon from the extras
folder at the position 100,100 without a highlight icon and run "firefox" when it's pressed (note that
these buttons also adheres to switches like <code>--outputonly</code>). If you use a negative x or y
value the icon will be placed relative to the other side of the screen. So the command
<code>--button "./extra/firefox.png;;-100,-100;firefox"</code> will put the same icon in the bottom
right corner.</p>

<p>If you want to use xlunch to for example choose a password you can use the <code>--clearmemory</code>
mode. This will set all the data for the entries to NULL when they are destroyed (ie. xlunch closes
or a new set of data is passed over stdin, see below). This is not bulletproof, all the data will still
be stored in plaintext in memory while xlunch is running, but it's better than nothing.</p>

<p>When loading fonts xlunch will look for them in the folders: <code>~/.local/share/fonts</code>,
<code>~/.fonts</code>, <code>/usr/local/share/fonts</code>, <code>/usr/local/share/truetype</code>,
and <code>/usr/local/share/TTF</code>. Imlib however does not search recursively, so to load a font
in for example <code>~/.local/share/fonts/FontFamily/FontName.ttf</code> in size 10 we would have to
pass <code>-f "FontFamily/FontName/10"</code>.</p>


<p><strong>Multi monitor setup</strong></p>

<p>xlunch does not know how to detect your output monitors, it sees your monitors
as a big single screen. If you run it, your window manager positions the window and makes
it fullscreen, so it is up to your window manager to decide what monitor xlunch runs on.
If you, however configure your WM to make xlunch floating, start xlunch in Desktop mode
(which bypasses your window manager) or if you do not have any WM at all, you can customize
the size and position of the window manually by providing the top/left coordinates and
width/height of your monitor screen, which effectively positions xlunch on the desired
place/monitor. Use the following options:</p>

<pre><code>-x, --xposition [i]               The x coordinate of the launcher window,
                                  use negative number to align from right
-y, --yposition [i]               The y coordinate of the launcher window,
                                  use negative number to align from bottom
-w, --width [i]                   The width of the launcher window
-h, --height [i]                  The height of the launcher window
</code></pre>

<p>For example, if you have two 800x600 monitors side by side, xlunch sees it as 1600x800.
You can put it to first monitor by: <code>-x 0 -y 0 -w 800 -h 600</code>, or to second monitor by
using <code>-x 800 -y 0 -w 800 -h 600</code>. Remember that all these settings might be overridden
by your window manager unless you start xlunch in Desktop mode. Another thing that is helpful
is that xlunch sets three distinct <code>WM_CLASS</code> values, "xlunch-fullscreen" for it's
default mode, "xlunch-desktop" for the desktop mode, and "xlunch-windowed" for it's windowed mode.
This makes it easy to tell your window manager to treat each of the different kinds properly.
Alternatively you can use the <code>--name</code> option or the environment variable
<code>RESOURCE_NAME</code> to set the first part of <code>WM_CLASS</code>, note however that this
value is also the program called by :recur.</p>

<p><strong>Compile:</strong></p>

<pre><code>make
make test
make install
</code></pre>

Uninstall with <code>make remove</code>

<p><strong>Entries file:</strong></p>

xlunch can accept entries to show either over stdin or through a file. The format used in both cases are:</p>

<pre><code>title;icon_path;cmd
title;icon_path;cmd
title;icon_path;cmd
title;icon_path;cmd
</code></pre>

<p><code>title</code> is the name of the program which will be shown, <code>icon_path</code> is a
path to an icon to show for the entry (png or jpg), and <code>cmd</code> is the command to be run
or returned when this entry is selected. To allow complex bash commands using semi-colons xlunch
simply parses the <code>cmd</code> field until a new-line is encountered. By default xlunch will
show a ghost icon if the icon you specified couldn't be found, if you want to not have an icon you
can simply leave the icon field empty (ie. <code>title;;cmd</code>). If you want to run xlunch from
within xlunch, for example to create a menu hierarchy, you should use a special syntax. This syntax
allows xlunch to replace its old process with the new one so you only have a single instance of
xlunch running and don't get any overhead from running it through bash. In order to do this simply
use the internal recur command by putting <code>:recur [options]</code> as the <code>cmd</code>
field. This will reuse the program name you originally used to call xlunch with but replace the
options with anything you add after recur. If you want to run a program by the name recur, simply
add a space in front of it. NOTE: recur relies on splitting the list of arguments, this is currently
only done on spaces, even those inside quotes, so it's not possible to pass arguments with spaces in
them when using recur (this is how previous versions of xlunch did all launching).
</p>

<p>
The <code>:recur</code> command shown above is a special class of commands called an "internal
command". All exec fields, both in entries, buttons, and otherwise that starts with a colon is
treated as an internal command (if you wish to avoid this simply add a space in front of the colon).
Apart from <code>:recur</code> the internal commands are:
<pre><code>
:scroll <pos>         Scroll to the given position. pos can be "top", "bottom", the row number,
                      or a number starting with + or - which is parsed as a relative scroll.
:hover <entry>        Set the entry as hovered and scroll to it. entry cas be "start", "end",
                      the entry number (1 indexed, 0 for no entry), or +/- like scroll.
:exec <command>       Runs the given command, even when outputonly is enabled
:print <string>       Prints a string to stdout
:quit                 Quits out of xlunch
</code></pre>
Internal commands can be chained, so one can do <code>:scroll +3 :print "Scrolled!"</code>. For <code>
print</code> and <code>exec</code> the argument needs to be enclosed in double-quotes if you want to
chain them, otherwise they will exec/print everything that follows. Because of this <code>quit</code>
can be put in front of a statement and wont quit until after all commands are run. So
<code>:quit :exec myProgram --help</code> will run myProgram with it's help flag, then quit. The same
can also be achieved with double quotes <code>:exec "myProgram --help" :quit</code>.
NOTE: Scroll is not completely implemented yet, <code>bottom</code> doesn't do anything and you are
able to scroll past the top and bottom of the list. This will not be possible in the future.
</p>

<p>If a completely empty line is encountered (ie. two sequential newlines), then all entries read
up until that point will be removed and only entries after this empty line will appear. This is a
feature that is intended for interfacing with xlunch from other scripts. There are many programs
that create this kind of output, like for example Conky, which can be piped directly to xlunch.
Sometimes you want new output to appear on the top of the list instead of at the bottom, to achieve
this you can use the <code>--reverse</code> switch. To add entries yourself you can create a named
pipe and keep it open while starting xlunch. xlunch will then read from this pipe and update the
entries on the fly. So you can write a script that passes entries to this pipe and they will appear
in xlunch, and all entries can be removed by passing two newlines in a row. Example:</p>

<pre><code>mkfifo /tmp/xlunch-input # Create a named pipe
cat > /tmp/xlunch-input & # Ensure that the pipe stays open
cat entries.dsv > /tmp/xlunch-input & # Write some initial data to the pipe
# This is neccesarry to avoid xlunch seeing the pipe as empty
cat /tmp/xlunch-input | xlunch & # Start xlunch in the background, reading from the pipe
echo "Hello;<icon path>;notify-send 'Hello from xlunch'" > /tmp/xlunch-input
# This last line will add the entry "Hello" to the already running xlunch menu
echo "Xlunch is great;;notify-send 'quite great indeed'" > /tmp/xlunch-input
# This adds yet another entry
echo -e "\nAll alone;;notify-send 'where did the others go?'" > /tmp/xlunch-input
# Because of the first character being a newline xlunch will clear the other
# entries and add this one as the only entry.
</code></pre>

<p>During compilation, a sample entries file is created for you. By default, this entries file is
installed into <code>/etc/xlunch/entries.dsv</code>. The file is created by reading the freedesktop
"Desktop Entry Specification" files (<code>.desktop</code>) found in
<code>$HOME/.local/share/applications</code> and <code>/usr/share/applications</code> these files
are read in priority so you can override the versions installed by your package manager by putting a
file with the same name in the user local directory. The file generated is static, so if you want to
add new programs to the list that xlunch sees then you could run the extras/genentries script again.
The output of this script is in the format expected from <code>entries.dsv</code> files and can be
customized to your needs and to create custom menus. When xlunch starts without the
<code>--input</code> flag, it first checks stdin to see if you have piped it any entries. If nothing
is found there it tries to load your entries file from <code>~/.xlunch/entries.dsv</code>. If this
fails, system-wide entries is loaded from <code>/etc/xlunch/entries.dsv</code>. By passing
<code>--input</code> the file specified is used instead and all other entries (including stdin) are
ignored.</p>

<p><strong>Example usage:</strong></p>

<pre><code># launcher mode:
xlunch --background wp.jpg --font "OpenSans-Regular.ttf/10" --input sample_entries.dsv

# desktop mode:
xlunch --background wp.jpg --font "OpenSans-Regular.ttf/10" --input sample_entries.dsv
    --desktop --multiple --noprompt --dontquit
</code></pre>

<p><strong>Tips and tricks:</strong></p>

<p>If you wish to run xlunch as app launcher, best practice is to
set up a keyboard shortcut to start xlunch, such as Alt+F2.
Or you can put a button in a taskbar to run it.</p>

<p>For example, to start xlunch on Alt+F2 in i3wm, add this line to ~/.i3/config:</p>

<pre><code>bindsym $mod+F2 exec /usr/bin/xlunch
</code></pre>

<p>To have xlunch running as a desktop with icons in i3wm, add this to ~/.i3/config:</p>

<pre><code>exec /usr/bin/xlunch --desktop --multiple --noprompt --dontquit
</code></pre>

<p>Note that you can also use the position flags from the multi-monitor section to display multiple
menus on your desktop.</p>

<p>xlunch is a perfect dmenu replacement, or rofi replacement.</p>


<hr>

        <p style='font-size: 13px;'>&copy; 2016, 2017, Tomas Matejicek - tomas [at] slax [dot] org & Peter Munch-Ellingsen - peterme [at] peterme [dot] net
        <br><br>
        <a href="http://www.freepik.com/free-photos-vectors/business">Business vector designed by Freepik</a>
        <br><br>

        </section>

      </div>
    </div>
  </body>
</html>
